<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

    <meta name="twitter:site" content="@metroui">
    <meta name="twitter:creator" content="@pimenov_sergey">
    <meta name="twitter:card" content="summary">
    <meta name="twitter:title" content="Metro 4 Components Library">
    <meta name="twitter:description" content="Metro 4 is an open source toolkit for developing with HTML, CSS, and JS. Quickly prototype your ideas or build your entire app with responsive grid system, extensive prebuilt components, and powerful plugins  .">
    <meta name="twitter:image" content="https://metroui.org.ua/images/m4-logo-social.png">

    <meta property="og:url" content="https://metroui.org.ua/v4/index.html">
    <meta property="og:title" content="Metro 4 Components Library">
    <meta property="og:description" content="Metro 4 is an open source toolkit for developing with HTML, CSS, and JS. Quickly prototype your ideas or build your entire app with responsive grid system, extensive prebuilt components, and powerful plugins  .">
    <meta property="og:type" content="website">
    <meta property="og:image" content="https://metroui.org.ua/images/m4-logo-social.png">
    <meta property="og:image:secure_url" content="https://metroui.org.ua/images/m4-logo-social.png">
    <meta property="og:image:type" content="image/png">
    <meta property="og:image:width" content="968">
    <meta property="og:image:height" content="504">

    <meta name="author" content="Sergey Pimenov">
    <meta name="description" content="Enhancement for standard HTML input control such as input[type=text], input[type=password], etc. Excellent to create the element for pin enter. The most popular HTML, CSS, and JS library in Metro style.">
    <meta name="keywords" content="HTML, CSS, JS, Metro, CSS3, Javascript, HTML5, UI, Library, Web, Development, Framework">

    <link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
    <link rel="icon" href="favicon.ico" type="image/x-icon">

    <link href="metro/css/metro-all.css?ver=@@b-version" rel="stylesheet">
    <link href="highlight/styles/github.css" rel="stylesheet">
    <link href="docsearch/docsearch.min.css" rel="stylesheet">
    <link href="css/site.css" rel="stylesheet">

    <title>Input - Metro 4 :: Popular HTML, CSS and JS library</title>
</head>
<body class="m4-cloak">

<header data-role="html-container" data-insert-mode="replace" data-html-source="header.html"></header>

<div data-role="html-container" data-insert-mode="replace" data-html-source="sidebar-menu.html"></div>

<div class="container-fluid docs-content">

    <div class="row flex-xl-nowrap">

            <div class="d-none d-block-xl cell-xl-2 order-2 border-left bd-light toc-wrapper">
                <h5>Table of contents</h5>
                <hr/>
                <ul class="toc-nav">
                    <li class="toc-entry"><a href="#">Input control</a></li>
                    <li class="toc-entry"><a href="#_input_about">About</a></li>
                    <li class="toc-entry"><a href="#_input_prepend">Prepend data</a></li>
                    <li class="toc-entry"><a href="#_input_append">Append data</a></li>
                    <li class="toc-entry"><a href="#_input_clear">Clear button</a></li>
                    <li class="toc-entry"><a href="#_input_reveal">Reveal button</a></li>
                    <li class="toc-entry"><a href="#_input_search">Search button</a></li>
                    <li class="toc-entry"><a href="#_input_history">History inputs</a></li>
                    <li class="toc-entry"><a href="#_input_custom_buttons">Custom buttons</a></li>
                    <li class="toc-entry"><a href="#_input_autocomplete">Autocomplete</a></li>
                    <li class="toc-entry"><a href="#_input_options">Options</a></li>
                    <li class="toc-entry"><a href="#_input_events">Events</a></li>
                    <li class="toc-entry"><a href="#_input_methods">Methods</a></li>
                    <li class="toc-entry"><a href="#_input_customize">Customize</a></li>
                    <li class="toc-entry"><a href="#_input_additional_classes">Additional classes</a></li>
                </ul>

            </div>

            <main class="cell-xl-10 order-1 pr-1-sx pl-1-sx pr-5-md pl-5-md">
                <div class="place-right d-none d-block-lg" style="width: 200px;">
                    <img src="images/logo.png" class="w-100" alt="">
                </div>

                <h1>Input control</h1>
                <p class="text-leader">
                    Enhancement for standard HTML input control.
                </p>

                <!-- ads-html -->

                <h3 id="_input_about">About</h3>
                <p>
                    In Metro 4, you can use enhancement version of input control.
                    To define it, add attribute <code>data-role="input"</code> to HTML input element.
                    You can assign role <code>input</code> to any text inputs: <code>text</code>, <code>password</code>, <code>email</code>, etc.
                </p>

                <div class="example">
                    <input type="text" data-role="input">
                </div>
                <pre><code>
                    &lt;input type="text" data-role="input"&gt;
                </code></pre>

                <h3 id="_input_prepend">Prepend data</h3>
                <p>
                    You can add prepend data to input field with attribute <code>data-prepend="..."</code>.
                </p>

                <div class="example">
                    <input type="text" data-role="input" data-prepend="User name: ">
                </div>
                <pre><code>
                    &lt;input type="text" data-role="input" data-prepend="User name: "&gt;
                </code></pre>

                <h3 id="_input_append">Append data</h3>
                <p>
                    You can add append data to input field with attribute <code>data-append="..."</code>.
                </p>

                <div class="example">
                    <input type="text" data-role="input" data-append=".00%">
                </div>
                <pre><code>
                    &lt;input type="text" data-role="input" data-append=".00%"&gt;
                </code></pre>

                <h3 id="_input_clear">Clear button</h3>
                <p>
                    When Metro 4 create input component, him add to element two special buttons: <code>clear-button</code> and <code>reveal-button</code>.
                    These buttons shown when input focused or user move mouse over input.
                </p>
                <p>
                    This button clear current value and flash it to default if default value is defined. You can set default value with attribute <code>data-default-value="..."</code>.
                    You can disable <code>clear-button</code> with attribute <code>data-clear-button="false"</code>.
                    You can change default icon for this button. To set your icon, use attribute <code>data-clear-button-icon="..."</code>.
                </p>
                <div class="example">
                    <p>Input</p>
                    <input type="text" data-role="input" class="">

                    <p>Input with default value 100</p>
                    <input type="text" data-role="input" data-default-value="100">

                    <p>Input without clear button</p>
                    <input type="text" data-role="input" data-clear-button="false">

                    <p>Custom clear button icon</p>
                    <input type="text" data-role="input" data-clear-button-icon="<span class='mif-cancel'></span>">
                </div>
                <pre><code>
                    &lt;p&gt;Input&lt;/p&gt;
                    &lt;input type="text" data-role="input" class=""&gt;

                    &lt;p&gt;Input with default value 100&lt;/p&gt;
                    &lt;input type="text" data-role="input" data-default-value="100"&gt;

                    &lt;p&gt;Input without clear button&lt;/p&gt;
                    &lt;input type="text" data-role="input" data-clear-button="false"&gt;

                    &lt;p&gt;Custom clear button icon&lt;/p&gt;
                    &lt;input type="text" data-role="input" data-clear-button-icon="&lt;span class='mif-cancel'&gt;&lt;/span&gt;"&gt;
                </code></pre>

                <h3 id="_input_reveal">Reveal button</h3>
                <p>
                    This button works with <code>input[type=password]</code> field.
                    When user press this button, him can see input value.
                    You can disable <code>reveal-button</code> with attribute <code>data-reveal-button="false"</code>.
                    You can change default icon for this button. To set your icon, use attribute <code>data-reveal-button-icon="..."</code>.
                </p>
                <div class="example">
                    <p>Input password</p>
                    <input type="password" data-role="input">

                    <p>Input without reveal button</p>
                    <input type="password" data-role="input" data-reveal-button="false">

                    <p>Custom reveal button icon</p>
                    <input type="password" data-role="input" data-reveal-button-icon="<span class='mif-lamp mif-2x'></span>">
                </div>
                <pre><code>
                    &lt;p&gt;Input password&lt;/p&gt;
                    &lt;input type="password" data-role="input"&gt;

                    &lt;p&gt;Input without reveal button&lt;/p&gt;
                    &lt;input type="password" data-role="input" data-reveal-button="false"&gt;

                    &lt;p&gt;Custom reveal button icon&lt;/p&gt;
                    &lt;input type="password" data-role="input" data-reveal-button-icon="&lt;span class='mif-lamp mif-2x'&gt;&lt;/span&gt;"&gt;
                </code></pre>

                <h3 id="_input_search">Search button</h3>
                <p>
                    You can enable <code>search-button</code> with attribute <code>data-search-button="true"</code>.
                    You can change default icon for this button. To set your icon, use attribute <code>data-search-button-icon="..."</code>.
                </p>
                <p class="text-bold">
                    When user press this button:
                </p>
                <ol class="decimal">
                    <li>If You define attribute <code>data-search-button-click="custom"</code>, Metro 4 execute your function, defined with attribute <code>data-on-search-button-click="..."</code></li>
                    <li>If you define attribute <code>data-search-button-click="submit"</code>, Metro 4 submit a form, where search input is defined</li>
                </ol>
                <div class="example">
                    <p>Default search button icon</p>
                    <input type="text" data-role="input" data-search-button="true">

                    <p>Custom search button icon</p>
                    <input type="text" data-role="input" data-search-button="true" data-search-button-icon="<span class='mif-rocket mif-2x'></span>">
                </div>
                <pre><code>
                    &lt;p&gt;Input without search button&lt;/p&gt;
                    &lt;input type="text" data-role="input" data-search-button="true"&gt;

                    &lt;p&gt;Custom search button icon&lt;/p&gt;
                    &lt;input type="text" data-role="input" data-search-button="true"
                        data-search-button-icon="&lt;span class='mif-rocket mif-2x'&gt;&lt;/span&gt;"&gt;
                </code></pre>

                <p>Define search button click event</p>
                <div class="example">
                    <script>
                        function mySubmitSearch(val){
                            alert('Custom submit function');
                        }
                    </script>
                    <form action="javascript:" onsubmit="alert('Form submit with self function');">
                        <p>Custom func</p>
                        <input type="text" data-role="input" data-search-button="true" data-search-button-click="custom" data-on-search-button-click="mySubmitSearch">

                        <p>Form submit func</p>
                        <input type="text" data-role="input" data-search-button="true">
                    </form>
                </div>
                <pre><code>
                    &lt;script&gt;
                        function mySubmitSearch(val){
                            alert('Custom submit function');
                        }
                    &lt;/script&gt;
                    &lt;form action="javascript:" onsubmit="alert('Form submit with self function');"&gt;
                        &lt;p&gt;Custom func&lt;/p&gt;
                        &lt;input type="text" data-role="input"
                            data-search-button-click="custom"
                            data-on-search-button-click="mySubmitSearch"&gt;

                        &lt;p&gt;Form submit func&lt;/p&gt;
                        &lt;input type="text" data-role="input"&gt;
                    &lt;/form&gt;
                </code></pre>

                <!-- ads-html -->

                <h3 id="_input_history">History</h3>
                <p>
                    Metro 4 input support <code>history</code> feature. To enable it feature, add attribute <code>data-history="true"</code> to input.
                    This enhance the input field that shows you the last input values that has been recently entered.
                    Use the up and down key's to scroll through previously typed input values. Use attribute <code>data-prevent-submit="true"</code> to cancel submitting form when user press <code>Enter</code>.
                </p>
                <div class="example">
                    <input type="text" data-role="input" data-history="true">
                    <p class="text-small">Enter value and press <kbd>Enter</kbd>, repeat, then press <kbd>Up</kbd> or <kbd>Down</kbd> arrows to access entered values.</p>
                </div>
                <pre><code>
                    &lt;input type="text" data-role="input" data-history="true"&gt;
                </code></pre>

                <h3 id="_input_custom_buttons">Custom buttons</h3>
                <p>
                    You can create custom button for input control with attribute <code>data-custom-buttons="..."</code>.
                    To add custom button, first-off - create array with your buttons and add array name as value for attribute <code>data-custom-buttons</code>.
                    This array must be created before input component initiated.
                </p>
                <div class="example">
                    <script>
                        var customButtons = [
                            {
                                html: "<span class='mif-user'></span>",
                                cls: "alert",
                                onclick: "alert('You press user button')"
                            },
                            {
                                html: "<span class='mif-cog'></span>",
                                cls: "warning",
                                onclick: "alert('You press cog button')"
                            }
                        ]
                    </script>

                    <input type="text" data-role="input" data-custom-buttons="customButtons">
                </div>
                <pre><code>
                    &lt;script&gt;
                        var customButtons = [
                            {
                                html: "&lt;span class='mif-user'&gt;&lt;/span&gt;",
                                cls: "alert",
                                onclick: "alert('You press user button')"
                            },
                            {
                                html: "&lt;span class='mif-cog'&gt;&lt;/span&gt;",
                                cls: "warning",
                                onclick: "alert('You press cog button')"
                            }
                        ]
                    &lt;/script&gt;

                    &lt;input type="text" data-role="input" data-custom-buttons="customButtons"&gt;
                </code></pre>
                <p>
                    Each button must be defined as object with three properties:
                        <code>html</code> - button caption,
                        <code>cls</code> - classes for custom button,
                        <code>onclick</code> - event for button when user clicked on it.
                </p>

                <h3 id="_input_autocomplete">Autocomplete</h3>
                <p>
                    You can create input with <code>autocomplete</code> feature. To create it, use attributes: <code>data-autocomplete</code>, <code>data-autocomplete-divider</code>, <code>data-autocomplete-list-height</code>.
                </p>
                <div class="example">
                    <input type="text" data-role="input" data-autocomplete="Ukraine, USA, Canada, Marokko, Singapur">
                    <p class="text-small">Begin type one of Ukraine, USA, Canada, Marokko, Singapur</p>
                </div>
                <pre><code>
                    &lt;input type="text" data-role="input" data-autocomplete="Ukraine, USA, Canada, Marokko, Singapur"&gt;
                </code></pre>

                <h3 id="_input_options">Options</h3>
                <table class="table cell-border table-border options-table mt-4">
                    <thead>
                    <tr>
                        <th>Option</th>
                        <th>Data-*</th>
                        <th>Default</th>
                        <th>Desc</th>
                    </tr>
                    </thead>
                    <tbody>
                    <tr>
                        <td><code>history</code></td>
                        <td><code>data-history</code></td>
                        <td>false</td>
                        <td>Enable history feature</td>
                    </tr>
                    <tr>
                        <td><code>historyPreset</code></td>
                        <td><code>data-history-preset</code></td>
                        <td></td>
                        <td>Preset values for history</td>
                    </tr>
                    <tr>
                        <td><code>historyDivider</code></td>
                        <td><code>data-history-divider</code></td>
                        <td>|</td>
                        <td>Divider for Preset values for history</td>
                    </tr>
                    <tr>
                        <td><code>preventSubmit</code></td>
                        <td><code>data-prevent-submit</code></td>
                        <td>false</td>
                        <td>Prevent submitting form when enabled history and user press <kbd>Enter</kbd> in input</td>
                    </tr>
                    <tr>
                        <td><code>defaultValue</code></td>
                        <td><code>data-default-value</code></td>
                        <td></td>
                        <td>Default value for input. Used when user click clear button or init input value</td>
                    </tr>
                    <tr>
                        <td><code>size</code></td>
                        <td><code>data-size</code></td>
                        <td></td>
                        <td>Set specific size for input</td>
                    </tr>
                    <tr>
                        <td><code>prepend</code></td>
                        <td><code>data-prepend</code></td>
                        <td></td>
                        <td>Add prepend label</td>
                    </tr>
                    <tr>
                        <td><code>append</code></td>
                        <td><code>data-append</code></td>
                        <td></td>
                        <td>Add append label</td>
                    </tr>
                    <tr>
                        <td><code>clearButton</code></td>
                        <td><code>data-clear-button</code></td>
                        <td>true</td>
                        <td>Add clear button to input</td>
                    </tr>
                    <tr>
                        <td><code>clearButtonIcon</code></td>
                        <td><code>data-clear-button-icon</code></td>
                        <td>&lt;span class='default-icon-cross'&gt;</td>
                        <td>Icon for clear button</td>
                    </tr>
                    <tr>
                        <td><code>revealButton</code></td>
                        <td><code>data-reveal-button</code></td>
                        <td>true</td>
                        <td>Add reveal button to input</td>
                    </tr>
                    <tr>
                        <td><code>revealButtonIcon</code></td>
                        <td><code>data-reveal-button-icon</code></td>
                        <td>&lt;span class='default-icon-eye'&gt;</td>
                        <td>Icon for reveal button</td>
                    </tr>
                    <tr>
                        <td><code>customButtons</code></td>
                        <td><code>data-custom-buttons</code></td>
                        <td></td>
                        <td>Array name with custom buttons</td>
                    </tr>
                    </tbody>
                </table>

                <h3 id="_input_events">Events</h3>
                <table class="table cell-border table-border options-table mt-4">
                    <thead>
                    <tr>
                        <th>Event</th>
                        <th>Data-*</th>
                        <th>Context</th>
                    </tr>
                    </thead>
                    <tbody>
                    <tr>
                        <td><code>onHistoryChange(val, history, index)</code></td>
                        <td><code>data-on-history-change</code></td>
                        <td>input</td>
                    </tr>
                    <tr>
                        <td><code>onHistoryUp(val, history, index)</code></td>
                        <td><code>data-on-history-up</code></td>
                        <td>input</td>
                    </tr>
                    <tr>
                        <td><code>onHistoryDown(val, history, index)</code></td>
                        <td><code>data-on-history-down</code></td>
                        <td>input</td>
                    </tr>
                    <tr>
                        <td><code>onClearClick(curr, new)</code></td>
                        <td><code>data-on-clear-click</code></td>
                        <td>input</td>
                    </tr>
                    <tr>
                        <td><code>onRevealClick(curr)</code></td>
                        <td><code>data-on-reveal-click</code></td>
                        <td>input</td>
                    </tr>
                    <tr>
                        <td><code>onInputCreate(el)</code></td>
                        <td><code>data-on-input-create</code></td>
                        <td>input</td>
                    </tr>
                    </tbody>
                </table>

                <h3 id="_input_methods">Methods</h3>
                <p>
                    You can use methods to interact with input component:
                        <code>getHistory()</code>,
                        <code>setHistory(history, append)</code> - history: array or string, append - bool,
                        <code>clear()</code>,
                        <code>toDefault()</code>,
                        <code>enable()</code>,
                        <code>disable()</code>,
                        <code>toggleState()</code>.
                </p>
                <pre><code>
                    var input = $(el).data('input');
                    input.clear();
                    input.toDefault();
                    input.toggleState();
                </code></pre>

                <!-- ads-html -->

                <h3 id="_input_customize">Customize</h3>
                <p>
                    You can customize your input with special attributes:
                </p>
                <table class="table cell-border table-border options-table mt-4">
                    <thead>
                    <tr>
                        <th>Option</th>
                        <th>Data-*</th>
                        <th>Desc</th>
                    </tr>
                    </thead>
                    <tbody>
                    <tr>
                        <td><code>clsComponent</code></td>
                        <td><code>data-cls-component</code></td>
                        <td>Additional classes for input control.</td>
                    </tr>
                    <tr>
                        <td><code>clsInput</code></td>
                        <td><code>data-cls-input</code></td>
                        <td>Additional classes for input element.</td>
                    </tr>
                    <tr>
                        <td><code>clsPrepend</code></td>
                        <td><code>data-cls-prepend</code></td>
                        <td>Additional classes for input prepend data.</td>
                    </tr>
                    <tr>
                        <td><code>clsAppend</code></td>
                        <td><code>data-cls-append</code></td>
                        <td>Additional classes for input append data.</td>
                    </tr>
                    <tr>
                        <td><code>clsClearButton</code></td>
                        <td><code>data-cls-clear-button</code></td>
                        <td>Additional classes for input clear button.</td>
                    </tr>
                    <tr>
                        <td><code>clsRevealButton</code></td>
                        <td><code>data-cls-reveal-button</code></td>
                        <td>Additional classes for input reveal button.</td>
                    </tr>
                    <tr>
                        <td><code>clsCustomButton</code></td>
                        <td><code>data-cls-custom-button</code></td>
                        <td>Additional classes for input custom button.</td>
                    </tr>
                    </tbody>
                </table>
                <div class="example">
                    <input type="text" data-role="input" data-cls-input="text-bold bg-dark fg-white text-center" data-clear-button="false" value="Test value">
                </div>
                <pre><code>
                    &lt;input type="text" data-role="input"
                        data-cls-input="text-bold bg-dark fg-white text-center"
                        data-clear-button="false"&gt;
                </code></pre>

                <h3 id="_input_additional_classes">Additional classes</h3>
                <p>
                    You can use additional classes to change input size: <code>.input-large</code> and <code>.input-small</code>.
                </p>
                <div class="example">
                    <div class="form-group">
                        <h5>Input small</h5>
                        <label>input</label>
                        <input type="text" class="input-small" value="Input value">
                        <label>data-role=input</label>
                        <input type="text" class="input-small" data-role="input" value="Input value">
                    </div>
                    <div class="form-group">
                        <h5>Input regular</h5>
                        <label>input</label>
                        <input type="text" value="Input value">
                        <label>data-role=input</label>
                        <input type="text" data-role="input" value="Input value">
                    </div>
                    <div class="form-group">
                        <h5>Input large</h5>
                        <label>input</label>
                        <input type="text" class="input-large" value="Input value">
                        <label>data-role=input</label>
                        <input type="text" class="input-large" data-role="input" value="Input value">
                    </div>
                </div>

            </main>
        </div>
    </div>

    <script src="docsearch/docsearch.min.js"></script>


    <script src="metro/js/metro.js?ver=@@b-version"></script>
    <script src="highlight/highlight.pack.js"></script>
    <script src="js/clipboard.min.js"></script>
    <script src="js/site.js"></script>
    <!-- ads-script -->
    <!-- ga-script -->
    <!-- hit-ua -->
</body>
</html>